TRANSACTIONS PLUGIN
--------------------
Authors: Mike Barlow


HOW TO USE
-----------

-------------------
TAKING MONEY
-------------------

How to use may vary dependent on the actual gateway / component being used but generally the functions you'd need to use to take payments are as follows.

To take a payment you will need to call the following function from the Transaction component:

$this->Transactions->takePayment($return, $model, $amount, $items, $extra = null, $user_id = null, $gateway = null);

The first parameter is an array of the urls to use for different actions such as return / cancel / success etc... These could be different based on what gateway you are using.

Second parameter is an array containing model and model_id as keys as a reference for what this transaction is for.

Third parameter is the amount to charge in total. Or it can be an array with elements of 'amount' for the total to charge and 'currency' if the currency code for this transaction needs to change from default specified in the config.

Fourth parameter is a multidimensional array of all the items that are part of this transaction, containing the following elements:
- description
- amount
- model
- model_id

Model / model_id could be left blank and will default to null if not needed, otherwise they can be filled in with something such as product and the product id each transaction item related to.

Fifth parameter is optional and is just an array allowing you to pass extra information to the gateways, each gateway may require different information passed here so consult each component incase any data needs to be passed here.

Sixth parameter is optional and allows you to specify a different user as the user making the transaction. As default it will be null and take the user from $this->Auth->user(), allowing this override allows things such as an admin to make an order in the backend on behalf of a user and have that transaction link correctly to the user rather then the admin id.

Seventh parameter is optional and allows you to specify a different gateway. E.G. You could have sagepay server setup but then in the admin want the option for a manual payment to log an order and say the user paid for it in cash on the premises.

The takePayment function will generally be used to setup the payment and redirect the user off site to take payment from them. The function does all however return data from a component as some gateways (such as stripe) do it all in the background with no need for moving off / reloading the page again.
As before, check the gateway as to whether you'd need to check this functions return value.

-------------------
CHECKING CALLBACKS
-------------------

If you are using a gateway which has redirected you to a different url, at some point it will come back to the site to log payment (to a url probably specified in the first parameter of the takePayment function), at this point you would use the following function:

$this->Transactions->checkPayment($gateway = null);

First and only parameter is optional, and as with takePayment allows you to check a certain gateway if you are using multiple gateways. Used so that any other gateway that's not default can access it's settings in the config when checking the payment callback.

This function will simply return a boolean true / false value as to whether it was successful. In the processing of this function it will also update the transactions table with success or failed and if needed it will populate the message field to give more information on why it failed.

Currently untested but during the process an id variable on the component should get prefilled with the transaction id. Access should be via $this->Transactions->id

-----

-------------------
SETTING UP GATEWAYS
-------------------

This section may require it's own readme if the number of gateways we support becomes large.

---------------------------
STRIPE
---------------------------

As default included are a stripe button element which will load up and assuming the correct parameters are passed to it, generate the stripe payment button.
Below is an example of an app specific element which sets up the amount and other parameters before calling the transactions stripe button.

	<?php
		$amount = Configure::read('SiteSetting.project_listing_costs');
		$tax_rate = Configure::read('Transactions.tax_rate');
		$amount_tax = $amount * $tax_rate;

		echo $this->Element(
			'Transactions.stripe_button',
			array(
				'dataAttr' => array(
					'name' => 'Me and My Builder',
					'currency' => 'GBP',
					'image' => '/theme/Site/img/payment-logo.png',
					'amount' => ($amount_tax * 100), //Stripe requires it's amount in the lowest currency format, in this case "pence"
					'description' => '&pound;' . number_format($amount_tax, 2) . ' project listing fee (&pound;' . number_format($amount, 0) . ' + VAT)',
					'label' => 'Accept Terms and Pay with Card',
					'email' => $data['Builder']['email'] // Clients email address
				)
			)
		);

General work flow for stripe would be to setup a form whose action would go to a function where the takePayment function would be called. Any input fields could be present here that you would need. No submit button would be needed as this would be provided with the Stripe Button.
Once the button is clicked the user will be presented with a popup upon which they enter the email (if not prefilled as above) and the credit card information. Once they submit this information stripe will setup the payment and if everything is OK, it will continue and submit the form allowing your code to then call the takePayment button which in turn will call the Stripe Component which will process the payment and check the return.
->checkPayment() is not needed for Stripe. You can just check the return of the takePayment function in order to determine if the payment was successfully taken:

	$transaction = $this->Transactions->takePayment( ... );

    $this->loadModel('Transactions.Transaction');
    $transaction_data = $this->Transaction->findById($transaction['transaction_id']);

	if (isset($transaction['result']) && $transaction['result']) {

		// Payment complete successfully, send any emails. Finalise the order. Display thank you screen

	} else {

		// problem, display error. Can check $transaction_data['Transaction']['message'] for information
	}

---------------------------
SAGEPAY SERVER
---------------------------

NOTE: Sagepay Server requires an extra table, found in /_assets/gateway_sql/sagepay_server.sql

An element is included for a sagepay button. All this needs to do though is submit a form to a page that has the takePayment().
As part of the sagepay component processing, it should eventually redirect to the nextUrl as specified by sagepay. Sagepay will then eventually return the user to a URL specified in the $return parameter of the takePayment function, this element should have a key of 'return'.

The return URL will then need to check the checkPayment function in order to check to see if the payment was a sucess.


---------------------------
MANUAL PAYMENT
---------------------------

The Manual Payment gateway works by simply creating a transactions record when takePayment is run. So in a similar way to the sagepay server, you can just have a button labelled manual payment which redirects to a page that just calls the takePayment function.

